//*********************************************************
//
//    Copyright (c) Microsoft. All rights reserved.
//    This code is licensed under the Apache License, Version 2.0.
//    THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF
//    ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY
//    IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR
//    PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.
//
//*********************************************************

namespace Microsoft.Research.eResearch.Blackboard.Interfaces
{
    using System;
    using System.Collections.Generic;
    using Microsoft.Research.eResearch.Blackboard.Common;

    /// <summary>
    /// Represents an abstract storage medium for the Blackboard to keep track of current
    /// subscribers and the types of BlackboardMessages in which they are interested.
    /// </summary>
    public interface ISubscriptionStore
    {
        /// <summary>
        /// Raised when the subscription store changes (i.e. when a subscriber subscribers or unsubscribes).
        /// This event is only raised if a subscriber subscription/unsubscription changes in such a way that all
        /// publishers must be notified of a new aggregate subscription profile.
        /// </summary>
        event EventHandler<EventArgs> SubscriptionStoreChanged;

        /// <summary>
        /// This method is used to add a new subscriber to the blackboard
        /// or to update the subscription profile of an existing subscriber.
        /// </summary>
        /// <param name="returnAddress">The URL for the subscriber to receive callbacks.</param>
        /// <param name="profile">The subscriber's requested subscription profile.</param>
        void Subscribe(Uri returnAddress, SubscriptionProfile profile);

        /// <summary>
        /// Deletes an existing subscriber from the blackboard.
        /// </summary>
        /// <param name="returnAddress">The subscriber's URL to unsubscribe.</param>
        void Unsubscribe(Uri returnAddress);

        /// <summary>
        /// Gets the aggregate subscription profile that the publisher can use.
        /// This profile is a set union of all of the items that subscribers have requested.
        /// </summary>
        /// <returns>The aggregate subscription profile.</returns>
        SubscriptionProfile GetAggregateProfile();

        /// <summary>
        /// This method takes an incoming BlackboardMessage and breaks up the name-value-pairs
        /// into distinct BlackboardMessages for each subscriber, depending on the subscriber's
        /// SubscriptionProfile.  
        /// </summary>
        /// <param name="incomingMessage">The incoming message.</param>
        /// <returns>A collection of BlackboardMessages and their destination URLs.</returns>
        IDictionary<Uri, BlackboardMessage> CreateNotificationMessages(BlackboardMessage incomingMessage);
    }
}
